home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 1 / Meeting Pearls Vol 1 (1994).iso / amok98-106 / amok98 / poster < prev    next >
Text File  |  1993-10-07  |  9KB  |  173 lines
  1. ===========================================================================
  2.                AMOK - Amiga Modula & Oberon Klub  Stuttgart
  3.  
  4.             "Poster": Norm bzw. Standardform für AMOK-Beiträge
  5.                Tips und Anhaltspunkte für Veröffentlichungen
  6. ===========================================================================
  7.  
  8. Einleitung
  9.  
  10. Wir  -AMOK-  sind  gerne  bereit,  auch  anderen  Modula-2-  bzw.   Oberon-
  11. Programmierern  mit  den  AMOK-Disks  einen  Weg zur Veröffentlichung Ihrer
  12. Programme  zu  bieten.   Ziel unserer PD-Reihe ist es schließlich, für eine
  13. möglichst  weite  Verbreitung von Modula & Oberon zu sorgen.  Da sich diese
  14. Programmiersprachen optimal zum Austausch von Programm-Modulen eignen, kann
  15. jeder  Programmierer  hierzu beitragen.  Je größer die Modulbibliothek ist,
  16. auf die ein Programmierer zurückgreifen kann, desto weniger muß er sich mit
  17. zeitraubenden Alltagsproblemen herumschlagen und sozusagen "das Rad zweimal
  18. erfinden".   Falls Sie also Module geschrieben haben, von denen Sie denken,
  19. daß  auch  andere  sie  gebrauchen  können, schicken Sie sie an AMOK.  Wenn
  20. irgend  möglich werden wir den Beitrag in unsere AMOK-Reihe aufnehmen.  Wir
  21. stellen  zwar  keine  Ansprüche  an die Genialität der Programme, damit Ihr
  22. Beitrag  eine  Chance  hat,  veröffentlicht zu werden, sollten Sie aber die
  23. unten  aufgeführten  Punkte  beachten.   Damit  gewährleistet ist, daß Ihre
  24. PD-Software auch wirklich brauchbar ist.
  25.  
  26.  
  27. 1) Kriterien
  28.  
  29. Wie  schon erwähnt stellen wir keine Anforderungen an das, was ein Programm
  30. besonderes  kann.   Das  was  es  kann,  soll  es aber sinnvoll und korrekt
  31. ausführen.   Ein  simples  aber  nützliches Modul hat, auch wenn es noch so
  32. banal ist, höhere Chancen, veröffentlicht zu werden, als ein Riesenprojekt,
  33. das an sich genial ist, aber ständig guru-meditiert.
  34.  
  35.  
  36. 2) AMOK Anforderungen
  37.  
  38. Die   Folgenden   Punkte   sind  verbindlich  und  von  jedem  AMOK-Beitrag
  39. einzuhalten:
  40.  
  41. * Zu  jedem  Modul(-packet)  gehört eine Dokumentation.  Ohne Dokumentation
  42.   sind  die  Module für andere unbrauchbar.  Es gibt auf den AMOK-Disketten
  43.   folgende Formen der Dokumentation:
  44.  
  45.     - Dokumentation  im Klartext in einer extra Datei mit der Endung ".dok"
  46.       (für deutsche Dokumentation) oder ".doc" (für die englische)
  47.  
  48.     - stichwortartige  Kurzbeschreibung  der Prozeduren im Definitionsmodul
  49.       Diese Form der Dokumentation ist in "HeaderInfo" genauer beschrieben.
  50.  
  51.   Die Dokumentation sollte mindestens diese Informationen beinhalten:
  52.     - Bedeutung und Auswirkung der Prozedurparameter
  53.     - Funktion und Verwendungszweck der Prozeduren
  54.     - Bedeutung der Rückgabewerte der Prozeduren
  55.     - Wichtige Hinweise über exportierte Variablen, Konstanten und Typen
  56.     - Hinweise auf mögliche Fehler (soweit bekannt)
  57.     - Angaben über eventuelle Einschränkungen oder Warnungen
  58.  
  59.   Wenn möglich sollte die Dokumentation nur in reinem ASCII-Code geschrieben
  60.   werden.  (MuchMore- und copy-to-prt:-verträglich)
  61.  
  62. * Der  Source-Code  sollte den Modulen immer beigefügt werden.  Schließlich
  63.   sollen  andere  Programmierer  aus  Ihrem  Programm  etwas lernen können.
  64.   Außerdem  ist  es somit möglich, eventuelle Fehler zu verbessern oder das
  65.   Programm  an  eigene Bedürfnisse anzupassen.  Als Ausnahmen sind folgende
  66.   zulässig:
  67.     - das  Programm ist wirklich ausgesprochen genial und gehört eigentlich
  68.       patentiert (es muß natürlich absolut fehlerfrei sein)
  69.     - die  Module  sind  Teile  eines  von  Ihnen  kommerziell vertriebenen
  70.       Programms, und Sie wollen nicht, daß jemand Einblick erhält
  71.     - Ihr  Programmierstil  ist  so  schlecht  und  Ihre  Methoden so haar-
  72.       sträubend,  daß  Sie  den  Source-Code  niemandem  zumuten wollen (In
  73.       diesem  Fall  sollten  Sie  sich  allerdings  Überlegen, ob Sie nicht
  74.       lieber C oder Assembler programmieren wollen)
  75.  
  76. * Definitions  und  Implementationsmodul  sollten  unseren Modulkopf (siehe
  77.   "HeaderInfo")  beinhalten.   Dieser  ist  zur  leichteren  Verwaltung der
  78.   inzwischen    mehrere    Megabyte   umfassenden   AMOK-Softwarebibliothek
  79.   notwendig.  Haltet  Euch an unsere Formatvorgaben in "HeaderInfo".
  80.  
  81. * Alle  Dateien und Unterdirectories sollen Icons haben, so daß Sie von der
  82.   Workbench  aus  leicht  zugänglich  sind.   Das Standardprogramm (Default
  83.   Tool)  von  Textdateien  (Source und Dokumentation) muß auf ":c/MuchMore"
  84.   eingestellt sein.
  85.  
  86.  
  87. 3) AMOK Vereinbarungen
  88.  
  89. Es wird gebeten, auch auf folgendes zu achten:
  90.  
  91. * Sollten  zum  Compilieren  eines  Moduls noch andere nicht standardmäßige
  92.   Module  benötigt  werden,  sollten  diese mitgeliefert werden.  Dabei ist
  93.   darauf  zu  achten,  daß  die  sym-Schlüssel stimmen, d.h.  alles mit der
  94.   selben  Version  der  Definitionsmodule compiliert wurde.  Existieren von
  95.   imortierten   Modulen  mehrere  Versionen,  dann  ist  anzugeben,  welche
  96.   benötigt wird. (Vermerk :Imports.)
  97.  
  98. * Im  Source-Code  und  in  der  Dokumentation  sollte man wenn möglich die
  99.   Zeilenlänge  auf  70  bis  75  Zeichen  begrenzen.   MuchMore und M2Emacs
  100.   akzeptieren  zwar  80  Zeichen, viele möchten jedoch sicherlich die Texte
  101.   ausdrucken, und da ist ein Rand ganz nützlich.
  102.  
  103. * Prozedur-,    Variablen-,   Konstanten-   und   Typenbezeichner   sollten
  104.   vorzugsweise  englisch sein, ebenso  die Kurzbeschreibung  der Prozeduren
  105.   (siehe AMOK#7, ProgInfo/StandardIDs).
  106.   Wenigstens  sollte  man  Englisch  und  Deutsch  nicht mischen.  Deutsche
  107.   Dokumentation sollte nicht fehlen, englische ist freiwillig.
  108.  
  109. * Kleine  Demoprogramme  dienen der leichteren Verständnis und dem besseren
  110.   Einarbeiten  in  die  Funktionen  eines Moduls.  Oft sind Testmodule oder
  111.   sonstige  Beispielanwendungen als Nebenprodukte eigener Programme sowieso
  112.   vorhanden.
  113.  
  114. * Seien  Sie  fair  gegenüber  anderen Programmierern.  PD heißt noch lange
  115.   nicht   "Software-Freiwild".    Wenn   Sie   Programmteile   von  anderen
  116.   übernehmen,   erwähnen   Sie   den  Autor  bitte  im  Modulkopf  oder  in
  117.   Kommentarzeilen.    Für   eine  kommerzielle  Nutzung  brauchen  Sie  die
  118.   Schriftliche  Erlaubnis  des  jewiligen Autors.  Denken Sie bitte auch an
  119.   eventuelle Shareware-Gebühren.
  120.  
  121.  
  122. 4) Zum Thema korrekte Programme
  123.  
  124. Die  folgenden Anweisungen gelten nicht speziell für AMOK-Disketten sondern
  125. sollten  von  allen  Programmierern beachtet werden.  Wenn diese Punkte für
  126. Sie noch nicht selbstverständlich sind, empfehlen wir Ihnen DRINGENDST Ihre
  127. Programme in Zukunft dementsprechend auszulegen.
  128.  
  129. * Alle  Programme  müssen  entsprechend  den  Richtlinien  der  ROM  Kernal
  130.   Reference Manuals programmiert sein.
  131.  
  132.   - Amiga User Interface Style Guide ISBN 0-201-57757-7, Addison-Wesley
  133.   - Amiga ROM Kernel Manual: Libraries ISBN 0-201-56774-1, Addison-Wesley
  134.   - Amiga ROM Kernel Manual: Includes & Autodocs ISBN 0-201-56773-3, A.-W.
  135.   - Amiga ROM Kernel Manual: Devices ISBN 0-201-56775-X, Addison-Wesley
  136.   - Amiga Hardware Manual ISBN 0-201-56776-8, Addison-Wesley
  137.   - The AmigaDOS Manual 3rd Edition ISBN 0-533-35403-5, Bantam Books
  138.  
  139.   - Native Developer's Update 2.0 (Examples, Debugging-Tools, Includes,
  140.                                    Autodocs)
  141.  
  142. * Alle  Programme  sollten  auf  korrektem Weg verlassen werden können, das
  143.   heißt,  ohne  neu  starten zu müssen, und so, daß uneingeschränkt weiter-
  144.   gearbeitet  werden  kann.   Außerdem  sollen  Sie alle Betriebsmittel und
  145.   Resourcen  an  das  System  zurückgeben  (Speicher deallozieren, Fenster,
  146.   Screens und Files schließen).
  147.  
  148. * Programme  sollten sich nicht so verhalten, als wären Sie die einzigen im
  149.   System,  sondern  auf  das Multitasking und seine Restriktionen Rücksicht
  150.   nehmen   (z.B.    gegenseitiger   Ausschluß   beim  Zugriff  auf  System-
  151.   strukturen).
  152.  
  153. * Programme  sollen  sich  gegenüber  dem Benutzer logisch und bei Fehlein-
  154.   gaben robust verhalten.
  155.  
  156. * Man sollte nie davon ausgehen, immer alle Betriebsmittel zu bekommen, die
  157.   man  anfordert.   Programme  sollen  sich  definiert verhalten, wenn z.B.
  158.   Files  nicht  geöffnet  werden  können, oder nicht mehr genügend Speicher
  159.   vorhanden ist.
  160.  
  161. * Die  Benutzerschnittstelle  soll den beim AMIGA allgemein üblichen Richt-
  162.   linien entsprechen (siehe Amiga User Inteface Style Guide).
  163.  
  164. * Programme   sollten  wenn  möglich  keine  spezielle  Gerätekonfiguration
  165.   vorraussetzen.
  166.  
  167. * Besonders  für die Entwicklung zukünftiger Bibliotheksmodule ist wichtig,
  168.   daß  die  Prozeduren  reentrant  sind,  falls  es  sinnvoll  ist, sie von
  169.   mehreren  Tasks  aus  gleichzeitig zu benutzen (es ist in Modula ja nicht
  170.   möglich, Module zweimal zu importieren).
  171.  
  172. --- Viel Spaß
  173.